home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / SciAn / technotes / STF_File_Reader < prev   
Text File  |  1994-08-01  |  7KB  |  162 lines
  1. STF File Reader
  2. Eric Pepke, Tzong-Yow Hwu
  3. September 22, 1992
  4.  
  5. Summary: Description of file format read by STF file reader
  6.  
  7. 1.0  Introduction
  8.  
  9. This document describes the STF format as used in SciAn versions 0.64 or 
  10. later.
  11.  
  12. The STF (Simple Text File) provides a file format to store a variety of
  13. datasets defined over structured grids.  Someday it will be able to do
  14. nonstructured grids as well.
  15.  
  16. An STF file is a text file containing statements separated by newlines.
  17. Each statement begins with a single word token at the beginning of the
  18. line which gives the purpose of the statement.  The statement may have
  19. arguments, which appear after the statement token.  For most statements,
  20. all the arguments must appear on the same line as the statement.
  21. Exceptions are noted later.  Normally, all of the statements in a single
  22. file put= together a single dataset or timestep of a dataset.  However,
  23. you can use the END statement to separate several datasets or timesteps
  24. within a single file.
  25.  
  26. Any line that begins with a hash mark (#) is assumed to be a comment and
  27. is ignored.  Currently, lines CANNOT be extended using the backslash (\).
  28.  
  29. The STF file stores scalar or vector data defined over regular or
  30. curvilinear grids.  Data may be time-dependent or eternal.  There may
  31. be missing data.
  32.  
  33. STF files should have a file extension of .stf to be recognized by SciAn.
  34.  
  35. 2.0  Some background concepts
  36.  
  37. In order to understand how the STF reader works, it is important to
  38. understand some background concepts about grids and datasets.  Most of
  39. this information is described in the SciAn user manual, but it is
  40. summarized here.
  41.  
  42. The kind of datasets that STF can read are made up of data defined over
  43. grids.  The grid gives the location of the data points and connectivity
  44. between them.
  45.  
  46. For the purposes of STF, there are two types of grids: regular and
  47. curvilinear.  In a regular grid, all the cells are the same shape, and 
  48. the axes of the grid are aligned with the principal axes of the 
  49. Cartesian space.  In a curvilinear grid, each cell can be a different
  50. shape, and the axes in a grid can bend in space any way desired.
  51.  
  52. Grids (or lattices) have two kinds of dimensions: topological and
  53. spatial.  Some people call topological dimensions "computational"
  54. dimensions instead.  The topological dimensionality of a grid is
  55. given by how many numbers are needed to represent a unique point 
  56. on the grid.  The spatial dimensionality of a grid is given by 
  57. how many numbers are needed to represent the position of the points
  58. in space.
  59.  
  60. In regular grids, the topological dimensionality is always the same 
  61. as the spatial dimensionality.  In curvilinear grids, it need not be.
  62. For example, a grid over a flat sheet of rubber which locates points
  63. on the surface of the paper has two topological dimensions and two
  64. spatial dimensions.  However, if you wrapped that sheet of rubber 
  65. around a sphere to locate points on the surface of the sphere, you
  66. would have a grid still with two topological dimensions but three
  67. spatial dimensions.
  68.  
  69. The data defined over the grid can be scalar or vector.  For scalar
  70. datasets, there is just a single real number at each grid point.
  71. (E.g., temperature over an area of terrain)  For scalar datasets, 
  72. there are several numbers at each grid point.  (E.g., wind velocity
  73. within a cell of air)  Individual data points can be missing.
  74.  
  75. 3.0  Writing an STF file
  76.  
  77. Because I need to get this out as fast as possible, I'll write this
  78. section later.  It should be possible to figure out how to write an
  79. STF file just from the reference section.  Basically, you just write
  80. to the file all the statements you need.
  81.  
  82. 4.0  Reference
  83.  
  84. Here is a list of all the statements in the STF file format:
  85.  
  86. RANK <rank>
  87.     This gives the rank or topological dimensionality of the grid.
  88.     <rank> should be a single real number.  For example, a two-dimensional
  89.     grid should have RANK 2.
  90.  
  91. DIMENSIONS <dim1> <dim2> ...
  92.     This gives the dimensions of the grid.  There should be as many
  93.     dimensions as the number given by RANK.  For example, a 20 by 50
  94.     grid should have DIMENSIONS 20 50.
  95.  
  96. BOUNDS <xmin> <xmax> <ymin> <ymax> ...
  97.     This gives the bounds, or the extent within the Cartesian space,
  98.     of the grid.  This can also be thought of as the smallest box with
  99.     the same spatial dimension of the grid that can fit around the grid.
  100.     There must be as many pairs as the spatial dimensionality of the grid.
  101.     If GRID (described later) is specified, this is the number of components
  102.     of the grid.  Also, if GRID is specified, the BOUNDS may be omitted, in
  103.     which case they will be calculated automatically.  If GRID is not
  104.     specified, this is assumed to be the same as RANK and a regular grid is
  105.     constructed from BOUNDS, DIMENSIONS, and RANK. 
  106.  
  107. NAME <name>
  108.     This gives the name of the dataset.  If it is not present, the name of
  109.     the file is used.
  110.  
  111. SCALAR
  112.     This specifies that the DATA to follow is scalar data.  See VECTOR.
  113.  
  114. VECTOR <n components>
  115.     This specifies that the DATA to follow is vector data, with a number of
  116.     components given by the real number <n components>.  VECTOR is also used
  117.     before a GRID to specify the number of components, and thus the number
  118.     of spatial dimensions in the grid.
  119.  
  120. ORDER COLUMN
  121. ORDER ROW
  122.     These specify column- or row-major ordering for data in subsequent 
  123.     DATA or GRID statements.  The default is column-major ordering.
  124.  
  125. INTERLACED
  126. NONINTERLACED
  127.     These specify whether subsequent vector data in a DATA or VECTOR statement
  128.     is interlaced or not.  In non-interlaced data, all the first components
  129.     in the dataset appear, then all the second components, and so on.  In 
  130.     interlaced data, all components for the first grid point appear, then
  131.     all components for the second, and so on.
  132.  
  133. TIME <time>
  134.     This specifies that the dataset is a single time step of the whole 
  135.     dataset at <time>, where <time> is a real number.  Multiple time steps
  136.     in separate files can be used to make a time-dependent dataset.  If there
  137.     is no TIME statement, the the dataset is assumed to be eternal.
  138.  
  139. DATA
  140.     <data>...
  141.     This gives all the data for the dataset in the order defined by ORDER
  142.     and INTERLACED or NONINTERLACED.  The data is freeform text real numbers
  143.     separated by spaces, beginning on the line right after DATA and 
  144.     continuing until all the data has been given.  Each data point may be
  145.     the word "missing" or just the letter "m" to specify that the data is
  146.     missing at that point.  (Don't put the quote marks in the file).
  147.  
  148. GRID
  149.     <grid data>
  150.     The format of this is just like DATA, but it gives vector data
  151.     specifying the positions of all the grid points.  This MUST be vector
  152.     data, and a VECTOR statement MUST precede the GRID statement.
  153.  
  154. END
  155.     Specifies the end of a dataset.  After an END occurs, you can start a new
  156.     dataset.
  157.  
  158. 5.0  Examples
  159.  
  160. There are several examples of stf files in the demo directory.  They all
  161. end in .stf.
  162.